home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / C / Applications / Tcl-Tk 8.0 / Pre-installed version / MoreFiles 1.4.3 / C Headers / MoreDesktopMgr.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-24  |  15.7 KB  |  440 lines  |  [TEXT/MPS ]
  1. /*
  2. **    Apple Macintosh Developer Technical Support
  3. **
  4. **    A collection of useful high-level Desktop Manager routines.
  5. **    If the Desktop Manager isn't available, use the Desktop file
  6. **    for 'read' operations.
  7. **
  8. **    We do more because we can...
  9. **
  10. **    by Jim Luther and Nitin Ganatra, Apple Developer Technical Support Emeriti
  11. **
  12. **    File:    MoreDesktopMgr.h
  13. **
  14. **    Copyright © 1992-1996 Apple Computer, Inc.
  15. **    All rights reserved.
  16. **
  17. **    You may incorporate this sample code into your applications without
  18. **    restriction, though the sample code has been provided "AS IS" and the
  19. **    responsibility for its operation is 100% yours.  However, what you are
  20. **    not permitted to do is to redistribute the source as "DSC Sample Code"
  21. **    after having made changes. If you're going to re-distribute the source,
  22. **    we require that you make it clear in the source that the code was
  23. **    descended from Apple Sample Code, but that you've made changes.
  24. */
  25.  
  26. #ifndef __MOREDESKTOPMGR__
  27. #define __MOREDESKTOPMGR__
  28.  
  29. #include <Types.h>
  30. #include <Files.h>
  31.  
  32. #include "PascalElim.h"
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif
  37.  
  38. /*****************************************************************************/
  39.  
  40. pascal    OSErr    DTOpen(StringPtr volName,
  41.                        short vRefNum,
  42.                        short *dtRefNum,
  43.                        Boolean *newDTDatabase);
  44. /*    ¶ Open a volume's desktop database and return the desktop database refNum.
  45.     The DTOpen function opens a volume's desktop database. It returns
  46.     the reference number of the desktop database and indicates if the
  47.     desktop database was created as a result of this call (if it was created,
  48.     then it is empty).
  49.  
  50.     volName            input:    A pointer to the name of a mounted volume
  51.                             or nil.
  52.     vRefNum            input:    Volume specification.
  53.     dtRefNum        output:    The reference number of Desktop Manager's
  54.                             desktop database on the specified volume.
  55.     newDTDatabase    output:    true if the desktop database was created as a
  56.                             result of this call and thus empty.
  57.                             false if the desktop database was already created,
  58.                             or if it could not be determined if it was already
  59.                             created.
  60.     
  61.     Result Codes
  62.         noErr                0        No error
  63.         nsvErr                -35        Volume not found
  64.         ioErr                -36        I/O error
  65.         paramErr            -50        Volume doesn't support this function
  66.         extFSErr            -58        External file system error - no file
  67.                                     system claimed this call.
  68.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  69.                                     the Finder will fix this, but if your
  70.                                     application is not running with the
  71.                                     Finder, use PBDTReset or PBDTDelete
  72. */
  73.  
  74. /*****************************************************************************/
  75.  
  76. pascal    OSErr    DTGetAPPL(StringPtr volName,
  77.                           short vRefNum,
  78.                           OSType creator,
  79.                           short *applVRefNum,
  80.                           long *applParID,
  81.                           Str255 applName);
  82. /*    ¶ Find an application on a volume that can open a file with a given creator.
  83.     The DTGetAPPL function finds an application (file type 'APPL') with
  84.     the specified creator on the specified volume. It first tries to get
  85.     the application mapping from the desktop database. If that fails, then
  86.     it tries to find an application with the specified creator using
  87.     the File Manager's CatSearch routine. If that fails, then it tries to
  88.     find an application in the Desktop file.
  89.  
  90.     volName        input:    A pointer to the name of a mounted volume
  91.                         or nil.
  92.     vRefNum        input:    Volume specification.
  93.     creator        input:    The file's creator type.
  94.     applVRefNum    output:    The volume reference number of the volume the
  95.                         application is on.
  96.     applParID    output:    The parent directory ID of the application.
  97.     applName    output:    The name of the application.
  98.     
  99.     Result Codes
  100.         noErr                0        No error
  101.         nsvErr                -35        Volume not found
  102.         ioErr                -36        I/O error
  103.         paramErr            -50        No default volume
  104.         rfNumErr            -51        Reference number invalid
  105.         extFSErr            -58        External file system error - no file
  106.                                     system claimed this call
  107.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  108.                                     the Finder will fix this, but if your
  109.                                     application is not running with the
  110.                                     Finder, use PBDTReset or PBDTDelete
  111.         afpItemNotFound        -5012    Information not found
  112.     
  113.     __________
  114.     
  115.     Also see:    FSpDTGetAPPL
  116. */
  117.  
  118. /*****************************************************************************/
  119.  
  120. pascal    OSErr    FSpDTGetAPPL(StringPtr volName,
  121.                              short vRefNum,
  122.                              OSType creator,
  123.                              FSSpec *spec);
  124. /*    ¶ Find an application on a volume that can open a file with a given creator.
  125.     The FSpDTGetAPPL function finds an application (file type 'APPL') with
  126.     the specified creator on the specified volume. It first tries to get
  127.     the application mapping from the desktop database. If that fails, then
  128.     it tries to find an application with the specified creator using
  129.     the File Manager's CatSearch routine. If that fails, then it tries to
  130.     find an application in the Desktop file.
  131.  
  132.     volName        input:    A pointer to the name of a mounted volume
  133.                         or nil.
  134.     vRefNum        input:    Volume specification.
  135.     creator        input:    The file's creator type.
  136.     spec        output:    FSSpec record containing the application name and
  137.                         location.
  138.     
  139.     Result Codes
  140.         noErr                0        No error
  141.         nsvErr                -35        Volume not found
  142.         ioErr                -36        I/O error
  143.         paramErr            -50        No default volume
  144.         rfNumErr            -51        Reference number invalid
  145.         extFSErr            -58        External file system error - no file
  146.                                     system claimed this call
  147.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  148.                                     the Finder will fix this, but if your
  149.                                     application is not running with the
  150.                                     Finder, use PBDTReset or PBDTDelete
  151.         afpItemNotFound        -5012    Information not found
  152.     
  153.     __________
  154.     
  155.     Also see:    DTGetAPPL
  156. */
  157.  
  158. /*****************************************************************************/
  159.  
  160. pascal    OSErr    DTGetIcon(StringPtr volName,
  161.                           short vRefNum,
  162.                           short iconType,
  163.                           OSType fileCreator,
  164.                           OSType fileType,
  165.                           Handle *iconHandle);
  166. /*    ¶ Get an icon from the desktop database or Desktop file.
  167.     The DTGetIcon function retrieves the specified icon and returns it in
  168.     a newly created handle. The icon is retrieves from the Desktop Manager
  169.     or if the Desktop Manager is not available, from the Finder's Desktop
  170.     file. Your program is responsible for disposing of the handle when it is
  171.     done using the icon.
  172.  
  173.     volName        input:    A pointer to the name of a mounted volume
  174.                         or nil.
  175.     vRefNum        input:    Volume specification.
  176.     iconType    input:    The icon type as defined in Files.h. Valid values are:
  177.                             kLargeIcon
  178.                             kLarge4BitIcon
  179.                             kLarge8BitIcon
  180.                             kSmallIcon
  181.                             kSmall4BitIcon
  182.                             kSmall8BitIcon
  183.     fileCreator    input:    The icon's creator type.
  184.     fileType    input:    The icon's file type.
  185.     iconHandle    output:    A Handle containing the newly created icon.
  186.     
  187.     Result Codes
  188.         noErr                0        No error
  189.         nsvErr                -35        Volume not found
  190.         ioErr                -36        I/O error
  191.         paramErr            -50        Volume doesn't support this function
  192.         rfNumErr            -51        Reference number invalid
  193.         extFSErr            -58        External file system error - no file
  194.                                     system claimed this call
  195.         memFullErr            -108    iconHandle could not be allocated
  196.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  197.                                     the Finder will fix this, but if your
  198.                                     application is not running with the
  199.                                     Finder, use PBDTReset or PBDTDelete
  200.         afpItemNotFound        -5012    Information not found
  201. */
  202.  
  203. /*****************************************************************************/
  204.  
  205. pascal    OSErr    DTSetComment(short vRefNum,
  206.                              long dirID,
  207.                              StringPtr name,
  208.                              ConstStr255Param comment);
  209. /*    ¶ Set a file or directory's Finder comment field.
  210.     The DTSetComment function sets a file or directory's Finder comment
  211.     field. The volume must support the Desktop Manager because you only
  212.     have read access to the Desktop file.
  213.  
  214.     vRefNum    input:    Volume specification.
  215.     dirID    input:    Directory ID.
  216.     name    input:    Pointer to object name, or nil when dirID
  217.                     specifies a directory that's the object.
  218.     comment    input:    The comment to add. Comments are limited to 200 characters;
  219.                     longer comments are truncated.
  220.     
  221.     Result Codes
  222.         noErr                0        No error
  223.         nsvErr                -35        Volume not found
  224.         ioErr                -36        I/O error
  225.         fnfErr                –43        File or directory doesn’t exist
  226.         paramErr            -50        Volume doesn't support this function
  227.         wPrErr                –44        Volume is locked through hardware
  228.         vLckdErr            –46        Volume is locked through software
  229.         rfNumErr            –51        Reference number invalid
  230.         extFSErr            -58        External file system error - no file
  231.                                     system claimed this call.
  232.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  233.                                     the Finder will fix this, but if your
  234.                                     application is not running with the
  235.                                     Finder, use PBDTReset or PBDTDelete
  236.     
  237.     __________
  238.     
  239.     Also see:    DTCopyComment, FSpDTCopyComment, FSpDTSetComment, DTGetComment,
  240.                 FSpDTGetComment
  241. */
  242.  
  243. /*****************************************************************************/
  244.  
  245. pascal    OSErr    FSpDTSetComment(const FSSpec *spec,
  246.                                 ConstStr255Param comment);
  247. /*    ¶ Set a file or directory's Finder comment field.
  248.     The FSpDTSetComment function sets a file or directory's Finder comment
  249.     field. The volume must support the Desktop Manager because you only
  250.     have read access to the Desktop file.
  251.  
  252.     spec    input:    An FSSpec record specifying the file or directory.
  253.     comment    input:    The comment to add. Comments are limited to 200 characters;
  254.                     longer comments are truncated.
  255.     
  256.     Result Codes
  257.         noErr                0        No error
  258.         nsvErr                -35        Volume not found
  259.         ioErr                -36        I/O error
  260.         fnfErr                –43        File or directory doesn’t exist
  261.         wPrErr                –44        Volume is locked through hardware
  262.         vLckdErr            –46        Volume is locked through software
  263.         rfNumErr            –51        Reference number invalid
  264.         paramErr            -50        Volume doesn't support this function
  265.         extFSErr            -58        External file system error - no file
  266.                                     system claimed this call.
  267.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  268.                                     the Finder will fix this, but if your
  269.                                     application is not running with the
  270.                                     Finder, use PBDTReset or PBDTDelete
  271.     
  272.     __________
  273.     
  274.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, DTGetComment,
  275.                 FSpDTGetComment
  276. */
  277.  
  278. /*****************************************************************************/
  279.  
  280. pascal    OSErr    DTGetComment(short vRefNum,
  281.                              long dirID,
  282.                              StringPtr name,
  283.                              Str255 comment);
  284. /*    ¶ Get a file or directory's Finder comment field (if any).
  285.     The DTGetComment function gets a file or directory's Finder comment
  286.     field (if any) from the Desktop Manager or if the Desktop Manager is
  287.     not available, from the Finder's Desktop file.
  288.  
  289.     vRefNum    input:    Volume specification.
  290.     dirID    input:    Directory ID.
  291.     name    input:    Pointer to object name, or nil when dirID
  292.                     specifies a directory that's the object.
  293.     comment    output:    A Str255 where the comment is to be returned.
  294.     
  295.     Result Codes
  296.         noErr                0        No error
  297.         nsvErr                -35        Volume not found
  298.         ioErr                -36        I/O error
  299.         paramErr            -50        Volume doesn't support this function
  300.         rfNumErr            –51        Reference number invalid
  301.         extFSErr            -58        External file system error - no file
  302.                                     system claimed this call.
  303.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  304.                                     the Finder will fix this, but if your
  305.                                     application is not running with the
  306.                                     Finder, use PBDTReset or PBDTDelete
  307.         afpItemNotFound        -5012    Information not found
  308.         
  309.     __________
  310.     
  311.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  312.                 FSpDTGetComment
  313. */
  314.  
  315. /*****************************************************************************/
  316.  
  317. pascal    OSErr    FSpDTGetComment(const FSSpec *spec,
  318.                                 Str255 comment);
  319. /*    ¶ Get a file or directory's Finder comment field (if any).
  320.     The FSpDTGetComment function gets a file or directory's Finder comment
  321.     field (if any) from the Desktop Manager or if the Desktop Manager is
  322.     not available, from the Finder's Desktop file.
  323.  
  324.     spec    input:    An FSSpec record specifying the file or directory.
  325.     comment    output:    A Str255 where the comment is to be returned.
  326.  
  327.     Result Codes
  328.         noErr                0        No error
  329.         nsvErr                -35        Volume not found
  330.         ioErr                -36        I/O error
  331.         paramErr            -50        Volume doesn't support this function
  332.         rfNumErr            –51        Reference number invalid
  333.         extFSErr            -58        External file system error - no file
  334.                                     system claimed this call.
  335.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  336.                                     the Finder will fix this, but if your
  337.                                     application is not running with the
  338.                                     Finder, use PBDTReset or PBDTDelete
  339.         afpItemNotFound        -5012    Information not found
  340.         
  341.     __________
  342.     
  343.     Also see:    DTCopyComment, FSpDTCopyComment, DTSetComment, FSpDTSetComment,
  344.                 DTGetComment
  345. */
  346.  
  347. /*****************************************************************************/
  348.  
  349. pascal    OSErr    DTCopyComment(short srcVRefNum,
  350.                               long srcDirID,
  351.                               StringPtr srcName,
  352.                               short dstVRefNum,
  353.                               long dstDirID,
  354.                               StringPtr dstName);
  355. /*    ¶ Copy the file or folder comment from the source to the destination object.
  356.     The DTCopyComment function copies the file or folder comment from the
  357.     source to the destination object.  The destination volume must support
  358.     the Desktop Manager because you only have read access to the Desktop file.
  359.     
  360.     srcVRefNum    input:    Source volume specification.
  361.     srcDirID    input:    Source directory ID.
  362.     srcName        input:    Pointer to source object name, or nil when srcDirID
  363.                         specifies a directory that's the object.
  364.     dstVRefNum    input:    Destination volume specification.
  365.     dstDirID    input:    Destination directory ID.
  366.     dstName        input:    Pointer to destination object name, or nil when
  367.                         dstDirID specifies a directory that's the object.
  368.     
  369.     Result Codes
  370.         noErr                0        No error
  371.         nsvErr                -35        Volume not found
  372.         ioErr                -36        I/O error
  373.         fnfErr                –43        File or directory doesn’t exist
  374.         wPrErr                –44        Volume is locked through hardware
  375.         vLckdErr            –46        Volume is locked through software
  376.         paramErr            -50        Volume doesn't support this function
  377.         rfNumErr            –51        Reference number invalid
  378.         paramErr            -50        Volume doesn't support this function
  379.         extFSErr            -58        External file system error - no file
  380.                                     system claimed this call.
  381.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  382.                                     the Finder will fix this, but if your
  383.                                     application is not running with the
  384.                                     Finder, use PBDTReset or PBDTDelete
  385.         afpItemNotFound        -5012    Information not found
  386.         
  387.     __________
  388.     
  389.     Also see:    FSpDTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  390.                 FSpDTGetComment
  391. */
  392.  
  393. /*****************************************************************************/
  394.  
  395. pascal    OSErr    FSpDTCopyComment(const FSSpec *srcSpec,
  396.                                  const FSSpec *dstSpec);
  397. /*    ¶ Copy the desktop database comment from the source to the destination object.
  398.     The FSpDTCopyComment function copies the desktop database comment from
  399.     the source to the destination object.  Both the source and the
  400.     destination volumes must support the Desktop Manager.
  401.     
  402.     srcSpec        input:    An FSSpec record specifying the source object.
  403.     dstSpec        input:    An FSSpec record specifying the destination object.
  404.     
  405.     Result Codes
  406.         noErr                0        No error
  407.         nsvErr                -35        Volume not found
  408.         ioErr                -36        I/O error
  409.         fnfErr                –43        File or directory doesn’t exist
  410.         wPrErr                –44        Volume is locked through hardware
  411.         vLckdErr            –46        Volume is locked through software
  412.         paramErr            -50        Volume doesn't support this function
  413.         rfNumErr            –51        Reference number invalid
  414.         paramErr            -50        Volume doesn't support this function
  415.         extFSErr            -58        External file system error - no file
  416.                                     system claimed this call.
  417.         desktopDamagedErr    -1305    The desktop database has become corrupted - 
  418.                                     the Finder will fix this, but if your
  419.                                     application is not running with the
  420.                                     Finder, use PBDTReset or PBDTDelete
  421.         afpItemNotFound        -5012    Information not found
  422.         
  423.     __________
  424.     
  425.     Also see:    DTCopyComment, DTSetComment, FSpDTSetComment, DTGetComment,
  426.                 FSpDTGetComment
  427. */
  428.  
  429. /*****************************************************************************/
  430.  
  431. #ifdef __cplusplus
  432. }
  433. #endif
  434.  
  435. #ifndef __COMPILINGMOREFILES
  436. #undef pascal
  437. #endif
  438.  
  439. #endif    /* __MOREDESKTOPMGR__ */
  440.